處理 .env 文件

.env 文件非常適合在本地開發應用程序時使用。Turborepo 不會將 .env 文件加載到你的任務運行時，而是留給你的框架或如 dotenv 這樣的工具處理。

然而，確保 Turbo 知道你的 .env 文件中的變數值變化，以便它可以用於哈希，這一點非常重要。如果你在構建之間更改了 .env 文件中的變數，構建任務應該錯過緩存。

為此，將文件添加到 inputs 鍵中：

{
  "globalDependencies": [".env"], // 所有任務的哈希
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.local"] // 僅 `build` 任務的哈希
    }
  }
}

.env 文件可以在環境變數尚未被添加到 env 鍵時，將變數加載到任務運行時。確保你在 CI 和生產構建中將你的環境變數添加到 env 鍵。

最佳實踐

• 在套件中使用 .env 文件：不建議在倉庫的根目錄使用 .env 文件。相反，我們建議將你的 .env 文件放在它們被使用的套件中。

  這種做法更接近你應用程序的運行時行為，因為環境變數在每個應用程序的運行時是獨立存在的。此外，隨著你的單一倉庫規模的擴大，這種做法使得管理每個應用程序的環境更加容易，防止環境變數在應用程序之間泄露。

  值得注意的是：當你逐步遷移到單一倉庫時，使用根目錄中的 .env 文件可能更容易。如 dotenv 之類的工具可以從不同位置加載 .env 文件。

• 使用 eslint-config-turboeslint-config-turbo 包可以幫助你找到代碼中使用的環境變數，這些環境變數未在你的 turbo.json 中列出。這有助於確保你的配置考慮到了所有環境變數。

• 避免在運行時創建或修改環境變數
  Turborepo 在任務開始時對環境變數進行哈希。如果你在任務運行時創建或修改環境變數，Turborepo 將不會知道這些變化，也不會在任務哈希中考慮它們。

  例如，Turborepo 將無法檢測到下面示例中的內聯變數：

{
  "scripts": {
    "dev": "export MY_VARIABLE=123 && next dev"
  }
}

MY_VARIABLE 是在 dev 任務開始後添加到環境中的，因此 turbo 將無法用它進行哈希。

以下是一些流行框架正確配置環境變數的範例：

Next.js

下面的 turbo.json 文件設定說明：

• 構建和開發任務將會因為 MY_API_URL 和 MY_API_KEY 的改變而有不同的哈希值。
• 構建和開發任務使用與 Next.js 相同的文件加載順序，.env 文件具有最高優先權。
• 測試任務不使用環境變數，因此省略了 env 鍵。（根據你的測試結構，你的測試任務可能需要一個 env 鍵。）

json複製程式碼
{
  "tasks": {
    "build": {
      "env": ["MY_API_URL", "MY_API_KEY"],
      "inputs": [
        "$TURBO_DEFAULT$",
        ".env.production.local",
        ".env.local",
        ".env.production",
        ".env"
      ]
    },
    "dev": {
      "inputs": [
        "$TURBO_DEFAULT$",
        ".env.development.local",
        ".env.local",
        ".env.development",
        ".env"
      ]
    },
    "test": {}
  }
}

Vite

對於使用 Vite 的項目，確保 turbo.json 中的環境變數和文件輸入反映了 Vite 的加載和緩存策略。通常，Vite 會利用 import.meta.env 來處理環境變數，你可能需要根據這個行為調整你的 env 配置。

故障排除

使用 -summarize

你可以在執行 turbo run 命令時添加 --summarize 標誌，這將產生一個 JSON 文件，總結你的任務的相關數據。檢查 globalEnv 和 env 鍵的差異可以幫助你識別可能遺漏的環境變數。

這個功能特別有助於當你發現任務在應該命中緩存的情況下沒有命中時。這可能是因為一個或多個關鍵環境變數未被正確計入或排除在哈希計算之外。利用 --summarize 功能，你可以深入了解任務配置和運行環境之間的具體差異，這有助於你優化配置並提高緩存的有效性。